Skip to content

docs(adr): ACP Server with WebSocket Transport#1258

Open
chaodu-agent wants to merge 2 commits into
mainfrom
docs/adr-acp-server-websocket
Open

docs(adr): ACP Server with WebSocket Transport#1258
chaodu-agent wants to merge 2 commits into
mainfrom
docs/adr-acp-server-websocket

Conversation

@chaodu-agent

@chaodu-agent chaodu-agent commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Proposes implementing an ACP (Agent Client Protocol) compliant server endpoint in OpenAB with WebSocket as the primary transport.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      ACP Clients                            │
├─────────────┬──────────────┬────────────┬───────┬──────────┤
│ IDE Plugin  │ Desktop App  │  Web App   │  CLI  │  Mobile  │
│ (Zed, JB)  │(AniCompanion)│ (Browser)  │       │          │
└──────┬──────┴──────┬───────┴─────┬──────┴───┬───┴────┬─────┘
       │             │             │          │        │
       └─────────────┴──────┬──────┴──────────┴────────┘
                            │
                   WSS  GET /acp  (JSON-RPC 2.0)
                            │
┌───────────────────────────┼─────────────────────────────────┐
│                    OpenAB Unified Binary                     │
│                           │                                 │
│  ┌────────────────────────▼────────────────────────────┐    │
│  │              ACP Server Adapter                      │    │
│  │  initialize / session/new / session/prompt           │    │
│  │  AgentMessageChunk / ToolCall / requestPermission    │    │
│  └────────────────────────┬────────────────────────────┘    │
│                           │                                 │
│  ┌────────────────────────▼────────────────────────────┐    │
│  │              Internal Dispatcher                     │    │
│  │         GatewayEvent / GatewayReply                  │    │
│  └───────┬────────────────┼────────────────┬───────────┘    │
│          │                │                │                │
│  ┌───────▼──────┐ ┌──────▼───────┐ ┌──────▼───────┐       │
│  │ Claude Agent │ │ Codex Agent  │ │  Kiro Agent  │       │
│  │  Container   │ │  Container   │ │  Container   │       │
│  └──────────────┘ └──────────────┘ └──────────────┘       │
│                                                             │
│  Existing adapters (Discord, Telegram, LINE, etc.)          │
│  continue to work in parallel                               │
└─────────────────────────────────────────────────────────────┘

Why ACP?

  • Industry standard — backed by Zed, JetBrains, GitHub, Block (3.5k★ spec repo)
  • Bidirectional — agent can request permission, push tool status, initiate messages
  • Any client connects — IDE, desktop app, web app, CLI — no bespoke adapters needed
  • Official SDKs — Rust, TypeScript, Python, Kotlin, Java

OAB's Unique Position

Existing ACP servers (Anvil, Goose, codex-acp):
  Local machine → stdio pipe → 1 agent process

OAB as ACP server:
  Remote clients → WebSocket → Multi-agent platform
                                 ├── Agent routing
                                 ├── Fan-out & aggregate
                                 ├── Session persistence
                                 ├── MCP bridging
                                 └── Tool policy engine

No one is building a remote multi-agent ACP server yet. This is OAB's differentiation.

What's in this PR

  • docs/adr/acp-server-websocket.md — full ADR with context, decision, consequences, alternatives considered, and phased implementation plan

Implementation Phases

  1. Core ACP Server (MVP) — WebSocket upgrade, initialize/session/prompt, streaming replies
  2. Tool Calls & Permissions — ToolCall notifications, requestPermission flow
  3. Multi-Session & Resume — multiple sessions per connection, session/load
  4. Multi-Agent Fan-Out — one prompt → multiple agents → aggregated result
  5. Streamable HTTP — POST+SSE fallback for serverless environments

References

cc @pahud

@chaodu-agent chaodu-agent requested a review from thepagent as a code owner June 30, 2026 03:22
@chaodu-agent

This comment has been minimized.

Sign in to view
@chaodu-agent

chaodu-agent commented Jun 30, 2026

Copy link
Copy Markdown
Collaborator Author

LGTM ✅ — Well-structured ADR with solid technical grounding for adopting ACP as the standard client protocol.

What This PR Does

Proposes adding an ACP (Agent Client Protocol) compliant server endpoint to OpenAB with WebSocket transport, replacing the need for bespoke per-frontend adapters with a single industry-standard protocol.

How It Works

A new GET /acp endpoint with WebSocket upgrade is added to the existing axum HTTP listener, using the official agent-client-protocol Rust crate for JSON-RPC dispatch. ACP lifecycle methods (initialize, session/new, session/prompt) map to OAB's internal GatewayEvent/GatewayReply flow, with agent routing via the model field. Feature-gated behind acp with Bearer token auth on upgrade.

Findings

# Severity Finding Location
1 🟢 Excellent strategic positioning — correctly identifies OAB's unique value as a remote multi-agent ACP server vs. existing local single-agent implementations §1 Context
2 🟢 Related ADR references (unified-binary.md, multi-platform-adapters.md) both exist on main — cross-references are valid §1 Related
3 🟢 Phased implementation plan is pragmatic — MVP first with progressive enhancement, deferring optional HTTP transport to Phase 5 §5 Implementation
4 🟢 Alternatives section is thorough — each rejected option (custom WS, OpenAI Realtime, MCP Streamable HTTP, per-frontend adapters) has clear justification §4 Alternatives
5 🟢 Correctly notes WebSocket transport RFD is in Draft status, honestly acknowledging spec dependency risk §3 Consequences
6 🟢 Clean feature-flag design with OPENAB_ACP_ENABLED and OPENAB_ACP_AUTH_KEY — non-invasive to existing adapters §2 Decision
What's Good (🟢)
  • Strategic clarity: The ADR identifies a genuine gap — no remote multi-agent ACP server exists — and positions OAB to fill it
  • Spec alignment: The proposed GET /acp with WebSocket upgrade matches ACP transport RFD conventions
  • Practical scope: Feature-gated, auth-gated, with graceful coexistence alongside existing adapters and the VTuber endpoint
  • Accurate cross-references: Both related ADRs (unified-binary.md, multi-platform-adapters.md) exist in docs/adr/ on main
  • Good risk acknowledgment: Honestly states spec dependency risk and current client adoption gap
  • Clean ADR structure: Follows standard Context → Decision → Consequences → Alternatives → Implementation format
  • Multi-agent fan-out vision: The ensemble dispatch concept (openab::ensemble) leverages OAB's existing multi-agent infrastructure in a novel way
Baseline Check
  • PR opened: 2026-06-30
  • Main already has: docs/adr/ directory with 20 existing ADRs (including referenced unified-binary.md and multi-platform-adapters.md)
  • Main does NOT have: any ACP-related code or documentation
  • Net-new value: First ADR establishing the architectural direction for ACP adoption — entirely new content, consistent with existing ADR corpus

@chaodu-agent chaodu-agent mentioned this pull request Jun 30, 2026
Open
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@thepagent thepagent Awaiting requested review from thepagent thepagent is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

pending-maintainer

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@chaodu-agent